3D Graphics Programming with QuickDraw 3D 1.5.4

Accessing File Objects

QuickDraw 3D provides routines that you can use to open file objects, access information about them, and read and write their data.

Q3File_OpenRead

You can use the Q3File_OpenRead function to open a file object for reading.



 
TQ3Status Q3File_OpenRead (

                     TQ3FileObject file, 

                     TQ3FileMode *mode);

file: A file object.
mode: On exit, a set of bit flags that specify the file mode of the specified file object. Set this field to NULL if you do not want a file mode to be returned.

DESCRIPTION

The Q3File_OpenRead function opens for reading the file object specified by the file parameter and returns, in the mode parameter, the file mode of the file object. See "File Mode Flags" for a description of the available file mode flags.

ERRORS

kQ3ErrorOSError kQ3ErrorOutOfMemory

Q3File_OpenWrite

You can use the Q3File_OpenWrite function to open a file object for writing.



 
TQ3Status Q3File_OpenWrite (

                     TQ3FileObject file, 

                     TQ3FileMode mode);

file: A file object.
mode: On exit, a set of bit flags that specify the file mode of the specified file object. Set this field to NULL if you do not want a file mode to be returned.

DESCRIPTION

The Q3File_OpenWrite function opens for writing the file object specified by the file parameter and returns the file mode of the file object in the mode parameter. See "File Mode Flags" for a description of the available file mode flags.

ERRORS

kQ3ErrorOSError kQ3ErrorOutOfMemory

Q3File_IsOpen

You can use the Q3File_IsOpen function to determine whether a file object is open.



 
TQ3Status Q3File_IsOpen (TQ3FileObject file, TQ3Boolean *isOpen);

file: A file object.
isOpen: On exit, a Boolean value that indicates whether the specified file is open (kQ3True ) or closed (kQ3False ).

DESCRIPTION

The Q3File_IsOpen function returns, in the isOpen parameter, a Boolean value that indicates whether the file object specified by the file parameter is open (kQ3True ) or closed (kQ3False ).

ERRORS

kQ3ErrorFileNotOpen kQ3ErrorInvalidObjectParameter kQ3ErrorNULLParameter

Q3File_Close

You can use the Q3File_Close function to close a file object.



 
TQ3Status Q3File_Close (TQ3FileObject file);

file: A file object.

DESCRIPTION

The Q3File_Close function closes the file object specified by the file parameter. Q3File_Close flushes any caches associated with the file and releases that memory for other uses. You should close a file object only when all operations on the file have completed successfully and you no longer need to keep the file object open.

ERRORS

kQ3ErrorFileInUse kQ3ErrorInvalidObjectParameter kQ3ErrorOSError

Q3File_Cancel

You can use the Q3File_Cancel function to cancel a file object.



 
TQ3Status Q3File_Cancel (TQ3FileObject file);

file: A file object.

DESCRIPTION

The Q3File_Cancel function removes from memory any data associated with the file object specified by the file parameter and disposes of the file object itself. You should call Q3File_Cancel when some fatal error occurs in your application or simply when you're finished using a file object. Once the file object has been canceled, you can no longer read data from it or write data to it. In all likelihood, the file object is corrupt after you call the Q3File_Cancel function.

ERRORS

kQ3ErrorInvalidObjectParameter kQ3ErrorOSError

Q3File_GetMode

You can use the Q3File_GetMode function to determine an open file object's current file mode.



 
TQ3Status Q3File_GetMode (

                     TQ3FileObject file, 

                     TQ3FileMode *mode);

file: A file object. This file object must be open.
mode: On exit, the current file mode of the specified file object.

DESCRIPTION

The Q3File_GetMode function returns, in the mode parameter, a set of flags that encodes the current file mode of the file object specified by the file parameter. See "File Mode Flags" for a complete description of the available file mode flags.

ERRORS

kQ3ErrorFileNotOpen kQ3ErrorInvalidObjectParameter kQ3ErrorNULLParameter

Q3File_GetVersion

You can use the Q3File_GetVersion function to get the version of an open file object.



 
TQ3Status Q3File_GetVersion (

                     TQ3FileObject file, 

                     TQ3FileVersion *version);

file: A file object.
version: On entry, a pointer to a file version. On exit, the current version of the specified file object.

DESCRIPTION

The Q3File_GetVersion function returns, through the version parameter, the current version of the file object specified by the file parameter.

ERRORS

kQ3ErrorFileNotOpen kQ3ErrorInvalidObjectParameter kQ3ErrorNULLParameter